3D GFX

home *** CD-ROM | disk | FTP | other *** search

/ 3D GFX / 3D GFX.iso / amiutils / i_l / jacosub / documentation / jscripts.doc < prev next >

Wrap

Text File | 1995-12-30 | 50KB | 984 lines

JACOsub 2.4 SCRIPT FILE FORMAT SPECIFICATION ============================================ Here is the complete JACOsub script file format specification. It's not complicated (unless you want it to be) and quite flexible. Check out the sample script (demo.js) that came with this software; it demonstrates many of the things you can do with a script. The accompanying file QuickRef.doc is a summary of this document, providing brief descriptions of the commands, escape codes, and directives that you can put into a script. CONTENTS OF THIS DOCUMENT ========================= 1. Basic format conventions 2. Compiler commands 3. Timed lines 4. Directives (for controlling timed lines) 5. Sample lines 6. Credits Most of the information in this document is demonstrated by the timed script demo.js, which is included in the JACOsub distribution archive. 1. BASIC FORMAT CONVENTIONS ============================ 1. Space characters (white space) may consist of spaces or tabs. Any line in a script file may contain any amount of white space in front of, behind, or in between parameters or words. 2. A line cannot be more than 511 characters in length (but you can concatenate several lines; see "escape codes" below). 3. Lines in the file may be blank lines, compiler commands, or timed lines for the script. All these are explained below. 4. Blank lines or lines containing white space only are ignored. 2. COMPILER COMMANDS ===================== Any line where # is the first non-space character is treated as a compiler command. The command is indicated by the next character or word (upper or lowercase) following the #. Some commands have arguments, which are assumed to begin with the next non-whitespace characters following the command. Anything shown here in square brackets [] are optional. The commands are: # (followed by a space) Comment. The line will be ignored. Example: # This is a comment. #C[LOCKPAUSE] <time> While a script is running, this command forces the clock to pause the clock at the time specified by <time>. Pressing a key will resume play. <time> is an offset from the beginning of the script in the form H:MM:SS.FF (hours:minutes:seconds.units). The beginning time of a script is usually 0:00:00.00 unless the script was included with an offset using the #I command. This command is useful for titling multiple laserdisc sides in a single script. Be warned: There will be no indication on the screen telling you that the script is paused! You have to keep track of your pauses yourself. #D[IRECTIVE][n] <directive string> Change some directive defaults (see the Directives section below), as in: #DVB8C10 or #directive3 hr50vmf2 or #d9JLJBC This command affects only those lines following it. Scripts may contain as many #D commands as you like. There are 21 default directives available for you to set. Specifying #D is the same as #D0 -- this sets the general overall default directive when a title line contains no directive or when just the D directive is present. The directives D1 - D20 may be set for situations when you need a shorthand way to represent a long complicated directive string in many places in your script. Directives D0-D20 are initially all identical, according to your DIRECTIVE config setting. #F[ONT] <n> <fontname.font> <size> [CLEAN or QUICK&DIRTY] [Y/X] This command sets font <n> to <fontname.font> which is <size> pixels high. Font settings affect the entire script. The <n> argument may range from 0 to 9 if the software has been registered, otherwise <n> may range from 0 to 3. #F commands should be specified before any timed lines in the script. CLEAN or QUICK&DIRTY indicate the rendering mode for the font. Normally, you should NEVER need to set the rendering mode! The program is smart enough to determine the best mode. Mono-color fonts will always be QUICK&DIRTY, and color fonts will be CLEAN only if the characters are designed to overlap. The Y/X argument modifies the default 1/1 aspect ratio for the font's height vs. width. It must be specified as two integers separated by a slash with no spaces, as in 40/33. This argument works only in AmigaDOS versions 2.0 or higher. NOTE: Due to the Amiga's internal font management, the Y/X parameter will affect only those fonts having names and/or sizes different from those fonts already loaded in memory. For example, the 36-pixel JACOsub font is loaded as font 0 when the program starts up, and its aspect ratio will be whatever it had when it loaded (see the FONT setting in the jacosub.cfg file). Any attempt to assign "jacosub.font 36" a different aspect will have no effect. You can get around this by setting the program configuration so that font 0 is something like Topaz 9, rebooting, and then using your script to load jacosub.font 36 with the desired aspect ratio. Example: #F 2 Diamond.font 20 #I[NCLUDE] <time> <filename> Include another script file <filename> into the current script, offsetting the second script's start time by <time>. <time> is always FORWARD offset. This command is useful, for example, if you are subtitling a series of TV shows having subtitles for credits and ending song lyrics. Rather than importing and/or re-timing the same sequences over and over again for each episode, you need only time the song lyrics once and the credits once, with the times starting at zero, and save these two scripts as separate files. When your "main" script includes these other scripts, they will be incorporated properly into the main script to start at the proper time (which is <time> added to the first time event in the included script), and any overlapping time ranges will be interwoven properly. <time> is specified in the form H:MM:SS.FF, where H is an hours digit, M is a minutes digit, S is a seconds digit, and F is a fractional-second digit. The units of F are determined by the #T command (below), and default to 30 units/second if the #T command was omitted (that is, the FF digits are SMPTE units ranging from 00 to 29). The included script may in turn contain its own, possibly different, #T command, and also its own #I commands. <time> always offsets the "includee" relative to the beginning of the "includer," taking into account the "includer's" own offset if the "includer" was itself included by some other script. <filename> may be any valid path + file name. <filename> can specify a complete path; if no path is specified then JACOsub will look in the default scripts directory, which you can set in the General Config menu. If you omit the extension in <filename>, then the program will include the script with the most recent time-stamp, among the extensions .js, .tts, .pjs, or .tim (.jsc, .pan, or .sub files won't be considered). The file name must not contain any spaces. Any occurrences of #F, #P, #Q, and #R in an included script will be ignored. These commands work only in the primary script, and they affect all included scripts. The effects of #D, #S, and #T commands are passed down into included scripts, but these commands inside an included script affect only that script and others IT might include; they have no effect on the higher-up "calling" scripts. Example: #I 0:21:44.16 scripts:kor/kor-credits.js On computers with small amounts of memory (1 megabyte or less), you may find that the memory reallocation fragmentation that occurs from having too many large included scripts may result in a memory overflow error message. If this happens, making your largest script the root script should help. #P[ALETTE] <color> <r> <g> <b> [palette] This sets the red, green, and blue intensities for color register <color>, to <r>, <g>, and <b>, respectively. This command may be specified anywhere in the file, but the setting will be used for the entire script. Use intensities of 14 or 15 with caution, as these are stronger than normal video signals, and can result in color bleeding when using in your genlocked video signal. Do not redefine color 2; JACOsub expects it to remain black. The optional [palette] parameter defaults to 0, and indicates the palette number in which to set the color. JACOsub has 10 palettes available. All 10 palettes are initialized to initial values set in the Playing / video Config menu. Palettes 1 - 9 may be used to reset temporarily certain colors for a particular display, using the CP directive. If JACOsub is using a 2-bitplane display, for example, you are restricted to 4 colors at any one time, but using multiple palettes allows you to redefine them on the fly. Examples: #P1 14 14 6 # set color 1 to yellow, in default palette 0 #p 3 0 13 0 1 # set color 3 to green, in palette 1 #Q[UANTIZE] [n] This command has the effect of eliminating timing gaps between subtitles of less than [n] time units, as specified by the #T command. Default is #Q0. Example: With #t30 and #q2 specified, any time event less than 2/30 seconds earlier than another time event will be rounded up to the later event. This is of questionable usefulness. If this command occurs before a #T command, then 30 units per second is assumed. Subsequent #Q commands replace earlier ones. Only the last #Q command in a script has any effect. #R[AMP] <seconds.units> If you play a pre-timed script, and discover a time drift, then use this command. The parameter <seconds.units> is the amount of drift to correct over the entire script. Script timings will be adjusted appropriately according to this value. A positive value will lengthen the total script running time, and a negative value will shorten the total script running time. The default value is #R0. The number after the decimal point is NOT a fractional second; it is the number of time units specified by #T. THIS COMMAND MUST NOT OCCUR BEFORE A #T COMMAND. Examples: #R-3.60 will shorten the script running time 3 seconds plus 60 time units. #R .92 will lengthen the script running time 92 time units. IMPORTANT: Your genlock affects the computer's internal clock. If you find that you have to ramp a 30-minute script more than 10 seconds, then you have a bad problem with your genlock. DO NOT TRY TO "FIX" THE PROBLEM WITH A BIGGER RAMP TIME! Doing so will result in math overflows, causing sudden jumps in timing. #S[HIFT] <[[hours:]minutes:]seconds.units> The parameter <seconds.units> is the amount to shift each time event in the script. A positive value will delay each time, and a negative value will advance each time. The default value is #S0. The number after the decimal point is NOT a fractional second; it is the number of time units specified by #T. THIS COMMAND MUST NOT OCCUR BEFORE A #T COMMAND. The first occurrence of #S in a script determines a global amount of shift, even if the first #S appears AFTER some timed lines. Subsequent occurrences affect only those lines following the #S. You must take care that your #S commands do not cause any times to be less than zero. The Amiga uses unsigned integers (always positive) for its internal representation of times, meaning that a time "less than" zero is actually a very large number! Example: #S -0.20 will cause ALL events to occur 20 time units sooner than usual, if this is the FIRST #S. Otherwise, all events SUBSEQUENT to this command will be shifted so that they occur 20 units sooner. #T[IMERES] <n> Time resolution; sets time units to <n> per second. The default is SMPTE units of 30 counts/second, as in #T30. If your script is in units 1/100 second units or PAL units, you must say so with the appropriate command, before the subtitle text begins. The #R or #S commands cannot precede a #T command. Examples: #t100 #TIMERES 25 3. TIMED LINES =============== Timed lines for the script may occur in any order. They look similar to this: H:MM:SS.FF H:MM:SS.FF directive {comment} text {comment} more text... For example: 0:30:57.22 0:30:59:46 vm {opening credit} A Film By Akira Kurosawa Here's what all those pieces are: Start time and stop time ------------------------ The first field is the time when the subtitle is to appear on the screen. The normal default is SMPTE format (that is, FF can range from 00 to 29). Use the #T command (described above) to define the units. IMPORTANT: The FF digits represent time units, NOT fractions of a second. There is a difference! For example, if you use #T10 to specify 1/10 second time units, then a time such as 0:00:00.60 would be illegal (and result in an error) because it specifies 60 time units! 0:00:00.6 or 0:00:00.06 or even 0:00:00.00006 would be correct for this case -- 6 UNITS are specified, not 6 tenths of a second. The second field is the time when the title is to disappear. If you prefer, you do not have to use the H:MM:SS.FF format at all. Instead, you can substitute a @ symbol followed by a single integer to represent total time units. For example, if #T30 is used to specify 1/30 second units, then the 0:05:10.22 is the same as @9322. This format is useful for representing times as video frame counts. Many laserdisc players display times in this fashion. Directive string ---------------- The next field is the directive. It is optional. If you leave it out, the program will default to standard subtitling form (all text centered at the bottom of the screen or depending on how you have your global default directive set in your configuration). The title text MUST begin with a non-alphabet character {such as a comment} if you omit the directive. Directives are explained fully in the DIRECTIVES section below. The first non-whitespace character following the directive is assumed to be the beginning of the subtitle text. Inline comments --------------- The {comment} is considered a part of the subtitle text, but it is ignored by the software. Use it for character names or keywords. A comment must be enclosed in braces. Comments may appear anywhere within the text of a subtitle. If you really want to to display a left brace, precede it with a backslash like so: \{. Right braces will be interpreted as a literal character or close of a comment, whichever seems appropriate. If a whitespace character immediately follows a comment closing brace, then that first whitespace character will be ignored. Any other kind of following character will be considered part of the subtitle text, and used. Comments in the text are especially useful when translating foreign films -- we use them to list possible translations of phrases we are not yet sure about. Title text ---------- In the example above, the "text" and "more text" fields are what get displayed. There are several special codes that you can put inside the text (CASE IS IMPORTANT HERE ONLY): \ Concatenate. If the LAST character in a line is a backslash, then JACOsub will concatenate the text on the next line to the text in the current line. Leading and trailing whitespace will be stripped from the concatenated text, so you can indent it if you wish. \n Newline. This is like a carriage return. A line containing this code will be split at the \n. Each of these new fragments will then be wordwrapped separately unless you turn wordwrapping off (see the W directive below). \n is useful for general formatting. Multiple \n codes may be concatenated to create blank lines. Example: Hello!\n\nHow are you?{blank line separating the two} \{ Display a left brace. Left braces are normally used to indicate the beginning of a comment. \~ Display a tilde. Tildes are normally used to create "hard" spaces (see below). \\ Display a backslash. Backslashes are normally used to denote these special codes. \N Normal. All text appearing after this code will be displayed in "normal" style. This is typically the default, unless you have the style (S) directive set to something other than normal. Note that this code is an uppercase \N -- a lowercase \n is a newline code. \I Italics. Display all text appearing after this code in italics. Example: \IHello!\N\nHow are you?{Hello is in italics} \B Boldface. This one isn't particularly useful, but go ahead if you feel like it. Text characters will be slightly fatter. \U Underline. This is virtually useless for large color text. \Cn Color n. The text following this code will be displayed using face color n. n is a hexadecimal digit; it may take the values 0-9 or A-F (or a-f). Typically, when using the font supplied with this software on a 2-bitplane display, only colors 3 and 1 are useful. See the CF directive below for some caveats about colors. \Fn Font n. The text following this code will be displayed using font number n. n may range from 0 to 9 (or 0 to 3 if the program is not registered). Normally you would use the F directive to set the default font for a line; use this escape code to override it. THE LAST 6 CODES ABOVE AFFECT ONLY ONE TIMING LINE; their effects do not carry over into other lines. These codes override any directives. The \I, \B, and \U codes are mutually exclusive: You can have bold text or italic text, but you cannot create text that is BOTH bold and italic. See the demo script file (demo.js) for good examples on usage. Leading or trailing space in subtitle text will be ignored. If you want to encode a true space on the ends of some text, use a tilde (~). It will be displayed as a space. To actually display a tilde, precede it with a backslash: \~. Tildes may also be used to create "hard"spaces; they will be displayed as spaces but text will not be wordwrapped on these spaces. White space between line arguments may consist of any amount of spaces or tabs. Each tab character inside the subtitle text will be converted to a space character. 4. DIRECTIVES ============== Directive strings were briefly described above, but there are so many that they deserve to be allocated a whole section of this document. A directive is a series of character codes strung together. A directive determines a subtitle's position, font, style, color, and so forth. Each character code begins with an alphabet character followed by arguments made up of other alphabet characters and numbers. Directives may contain any of the following codes, in any order. The directives may be uppercase or lowercase. Like the text codes above, directives only affect a SINGLE timing line; their effects do not carry over into other lines. Any parameters shown here in square brackets [] are optional. Vertical positioning -------------------- VA Continue this line directly Above the previous one. This is the opposite behavior of VU below. This is a useful directive for those cases where you want a new line to appear above the previous line's position, even if both lines do not share the same time range. See VU below for more details. VB[n] Bottom. Position last line at the bottom (default). The offset from the bottom of screen n is optional - it says how many raster lines to offset from the physical bottom-of-viewport. VB by itself is the same as VB16 (in the original default for this software). The default value of n can be changed using #D command or in the General Configuration settings. VHn Line height (i.e. spacing), where n is the percentage of the font height to use for line spacing. Default is 100 (single- spaced). Using 200 would result in double-spaced lines. n may range from -32768 to 32767, although the useful range is probably more like 50 to 500. VL[n] line n. Position subtitle starting at text line n (the height of a line depends on the font you use). n=0 is the top line. If n is negative or omitted, the line will appear in the same vertical position as the preceding timed line. VM[n] Middle. Text will be centered vertically in the area defined by the VTn and VBn directives. The optional parameter [n] is a positive or negative integer that will cause the centered block to be shifted up or down [n] lines (line height determined by the VH setting). VPn Pixel n. Position subtitle so that the font baseline of the first line of text is n pixels from the top of the viewport. You need to know your font's baseline position for this directive to be of any use. The mouse-positioning operation in the script editor creates directives like this. VSn Not yet implemented; doesn't do anything yet. Don't ask. VT[n] Top. Position the title with the first line at the top. The offset n is optional - as with VB, VT by itself is the same as VT16 in the original distribution of this software. VU Continue this line directly Underneath the previous one. This is useful if you want a line with different directives grouped in the same vertical-positioning block as the previous line. You can also use the VU directive to create interesting effects when a line with the VU directive is timed so that it is not on the same display as the previous line. For example, suppose you had a single line that used the VM directive. Normally it would be perfectly centered vertically on the screen. However, if a VU line follows it, both are positioned as if they were a block of lines to be centered on the screen together; i.e. the VM line will appear slightly above center and the VU line will appear slightly below center, regardless of WHEN they are individually displayed. Had VB been used instead of VM, the first line would have appeared raised one text line higher than bottom, just enough to make room for the second line. VA has the same effect as VU if the lines were in reverse order in the script. Horizontal positioning ---------------------- Margins: HLn Left margin. Set left margin at a position that is n% of the the screen width. Default is HL1 (1% from left edge). HRn Right margin. Set the right margin at a position that is n% of the screen width. Default is HL99 (1% from right edge). The right margin MUST be greater than the left margin. Text justification: JC Center. Text is centered within H constraints (normal default). JF[:p] Full. This aligns the left and right edges of text flush with the ends of the widest wordwrapped line in the text block. If you want the justified text to span the full margin width, set wordwrapping to W2 (greedy) instead of W1 (smart, the default). The :p is a position parameter. It may be :C (default), :L, :R, or :U, for Center, Left, Right, and Unconditional, respectively. :C, :L, and :R control the position of non-wordwrapped lines such as single short lines or the last line in a wordwrapped block -- these will not not be stretched to fit the block width. The :U parameter means "unconditional." JF:U is the same as JU. JF:U causes ALL lines in the block, wordwrapped or not, including the last line, to be stretched to fit exactly within the margins. JF:U is useful for titling credits like this: Clint Eastwood . . . . . . . Dirty Harry All the spaces will then be adjusted so that the line fits exactly inside the margins, and a list of these credits will have flush left and right edges. You will need to experiment with the number of dots and spaces to get it all to look good. You can also try elminating the spaces between the dots, or substituting dashes, for somewhat different effects. JF[:p] commandeers one character in each font for use as an adjustable space; the decimal character code used will be one of: 128, 31, or 127, whichever is available (hex codes 80, 1F, or 7F, respectively). The JF directive has no effect on fonts lacking all of these character codes. Mono-spaced fonts are likewise unaffected. JL Left. Align left edge of text at the HLn margin position. JR Right. Align the right edge of text at the HRn margin position. JU Obsolote directive, identical to JF:U Block justification: JBC Justify block center. Because of wordwrapping, the width of a text block will never occupy the full width specified in your margin settings. This directive positions the imaginary rectangle occupied by the text in the center of your margin settings, regardless of the text justification directives. For example, the JL directive by itself might produce the following effect (the | character indicates margin boundaries): | The quick brown fox | | jumped over the lazy dog. | but the JL directive together with JBC will preserve the text justification but center the block of text between the margins: | The quick brown fox | | jumped over the lazy dog. | AnimEigo video products have their subtitles displayed this way. JBF Justify block full (default). Text will be positioned according to whatever text justification directives are in effect, using the full width specified by the current margin settings. JBL Justify block left. Position the text block at the left margin. JBR Justify block right. Position the text block so that the right edge is at the right margin. Wordwrapping: W0 Disable automatic wordwrapping. This may result in your text not fitting within the position constraints defined with H & V. There is really NO reason at all why you would want to turn off wordwrapping; you can wrap words manually with the \n code whether wordwrapping is on or off. This directive is here just for the sake of completeness. W1 Automatic "smart" wordwrapping (default). Even if a your text contains newline codes, the separate substrings will be word- wrapped if necessary. This wordwrap mode uses a "smart" algorithm that attempts to minimize the area of the screen occupied by the title. In this mode, you will never see a line wrapped as shown (the | characters indicate margin boudaries): | The quick brown fox jumped over the lazy | | dog. | Instead, the W1 alghorithm will attempt to minimize the text area without using any extra lines, resulting in: | The quick brown fox | | jumped over the lazy dog. | This is easier for the viewer to read. Same margins, same number of lines, but the lines are more equal in length. W2 Automatic "stupid" (generally known as "greedy") wordwrapping. If you are disconcerted by words not completely filling the horizontal margin space, and you don't mind having a single word hanging by itself on the last line (as in the first W1 example above), then use this directive. This is the standard text-editor wordwrap algorithm, which makes no attempt at aesthetics. Why anybody would want to use this is beyond me, but here it is. \n codes behave the same as with W1. Fonts ----- Font rendering: Fn Use font n, where n is a number from 0 to 9 (JACOsub loads four fonts, which you can specify in the Config menu. The usual default font is 0, which is what you should use as your "primary" font. Fonts 4-9 are unavailable if the software is unregistered. FQ Quick&Dirty text. Text color 3 is always quick. Other colors must normally be rendered one character at a time to avoid interference between the shadow and face color, but only when the font is designed with overlapping characters. This interference happens because of a fault in the way the Amiga renders text. The FQ directive forces all text on a line to be rendered in quick mode as if it were color 3. You should never need to use the FQ directive. The program is smart enough to determine when a font can be quick&dirty. For example, JACOsub's 32- and 36-pixel fonts will default to clean mode because they have overlapping characters, but the 32-pixel font will default to Quick&Dirty because its characters do not overlap. FC Clean rendering. Only color 3 will be rendered fast, other colors will be rendered so that the face color is not disturbed. You can use this directive to negate, on a single line, a global FQ directive set using the #D command. Normally this directive will never be needed. The demo script demo.js tricks JACOsub into generating "slow" clean text in the foreground display so you can see how it is. If you are curious to see how the Amiga messes up color 1 text if it's displayed the quick way, run the demo after inserting the global command #DFQ at the top of the file demo.js before you play the demo. FD Default text rendering. Rendering will be "quick" or "clean" depending on how your font was set up in your configuration. This directive is useful for overriding a #DFC or #DFQ command. FOn[:a] Generate an outline around the font, n pixels wide. Color 2 (JACOsub's outline color) is used to generate the outline. This directive is useful for transforming a plain mono-color Amiga font into a nice titling font, especially when combined with the FS (font shadow) directive. Recommended value for n is 2, which produces a nice flicker-free outline. n must be less than 127. The default value is zero. The optional :a suffix indicates a color to use for anti- aliasing. This defaults to the anti-alias setting in the Playing / video configuration, typically 2 (no antialiasing). WARNING: Generating outlines can slow the program down considerably! It is recommended that you use this directive only with QUICK&DIRTY font rendering, preferably with mono-color fonts. An antialias color other than 2 will slow it down somewhat further. FSdn Generate a font shadow, taking into account any existing font outline, in direction d, and n pixels deep. Color 2 (JACOsub's shadow color) is used to generate the shadow. The direction d is specified as a compass direction: N, S, E, W, NW, NE, SW, SE. Good values to use for the shadow depth n are 2 - 5. The warning about font outlines above applies here also. Example: FSSE3 produces a shadow similar to the JACOsub 32- pixel font, with the shadow extending down and to the right. Font style (may also be set with \ codes in the title text): SN Normal style (typical default). SI Italic. SB Bold (using the JACOsub font, this doesn't look good with colors other than color 3). SU Underline (ugly! Not recommended). Font color (CFn may also be set with text codes): CFn Use color register n for the face color of the font. JACOsub assumes that all color fonts use bitplane 0 (i.e. color 1) for the face color, and bitplane 1 (i.e. color 2) for the shadow/ outline. THIS IS IMPORTANT! JACOsub will generate text differently depending on the color selected (see FF above). The foreground color may also be set using the \Cn code inside the text. CBn Use color register n for the background color. The display will be cleared to this color prior to building the text. If two lines share the same display, and they have different background colors specified, the screen will be cleared using the latest NON-ZERO background color that occurs for that display. In other words, non-zero colors override the default zero (transparent) background color. CPn Use color palette n for this display. Default value of n is 0, which is the primary color palette normally used by JACOsub. The values of n may range from 0 to 9, for a total of 10 color palettes. All 10 palettes are initially set to a master palette which can be modified in the Playing / video Config menu, and they can be modified with the #Palette script command. Because the palette is loaded immediately following a video buffer switch, the new imagery on the display will appear with the old palette momentarily. If this is too noticeable, then you should precede your alternate-palette lines with a "dummy" short-duration blank screen (containing a hard space) using your alternate palette, as in this example: 0:00:12.20 0:00:12.22 cp2 ~{palette 2 on blank screen, .02 sec} 0:00:12.22 0:00:14.50 cp2 This will appear with the new palette. CS[L]n[:s[:c]] This causes text to appear inside a shaded rectangle. The rectangle will be large enough to contain the text with a margin of n pixels on all sides. The shading is user-defined (see the Playing / video Config menu) if s=0, or solid if s=1. Color c will be used for the rectangle. The style (s) and color (c) paramters are optional; not setting them uses the defaults, normally s=0, c=2 (user-defined, black). Setting n=0 disables the shading. We suggest using n=8 or more. Without the [L] parameter described below, only ONE shaded background rectangle will appear on the screen; that is, JACOsub will attempt to create a SINGLE box which contains ALL text that uses the CS directive and shares the same display. If two shading directives for the same time range have conflicting parameters, one of the directives will be used, but predicting WHICH one is impossible. The normal default setting is CS0:0:2, which can be changed using the #D command. The optional [L] parameter causes each text segment (which might be split by wordwrapping) to be shaded in its own rectangle. This looks ugly for a block of wordwrapped text, but it is useful for shading separate single lines that overlap in time. Notes: Setting VB0 will mean that bottom-positioned text is as low as it will go, therefore shading cannot appear below it. You should set the VB directive so that there is room for the shading rectangle to extend below the text. Also, VB text will be repositioned slightly higher when the running clock is displayed during play, but shade boxes will NOT be repositioned. Genlock fader control --------------------- GBn[Tm] Move the background slider control to n% saturation over a time period of m/60 seconds of time. n may range from 0 to 100. If time specifier is omitted, it defaults to 0 (i.e. instant). Zero saturation is a normal transparent background, allowing the video signal to show through all areas corresponding to color 0 on the computer's display. Example: GB63T120 slides the background fader to 63% saturation in 2 seconds (120/60 seconds). GGn[Tm] Move the graphics slider control to n% saturation over a time period of m/60 seconds of time. 100% saturation is the normal operating mode (full graphics), whereas 0% results in only the video signal with no overlaid computer graphics. >> DO NOT USE GG OR GB IN DEFUALT DIRECTIVES, or the genlock will be having control signals sent to it at every time event. IFF graphic files ----------------- IL <ILBM file name> [<x offset %> <y offset %>] Load an IFF ILBM file (typically a brush file) into a video buffer for the time interval specified by the start and stop time. When this directive appears, JACOsub assumes that the remainder of the line is information about the file, NOT title text. The file name must follow the directive string. The position to display the image, specified as percent of screen width and height from the center, can be specified in the next two fields. These position coordinates default to 0 0 if they are omitted, which results in the picture being centered on the screen. The picture may be positioned to extend beyond the display edge. Any IFF ILBM picture or brush may be specified. As many as 40 images may be loaded onto a single screen. This enables you to create several small brushes and display them all at once, in different areas of the screen. CAVEATS (READ CAREFULLY!): 1. You need at least AmigaDOS 2.0 to use this directive. Under 1.3 and below, this directive is ignored unless you have a 1.3-compatible version of iffparse.library in your libs: directory. 2. You will not be informed if a file is too big to fit in memory. If this happens, the file will simply not load. 3. If the IFF file contains more bitplanes than the JACOsub video buffers, the EXTRA BITPLANES WILL BE IGNORED. You may change the number of JACOsub's bitplanes in the Playing / video Config menu. If you have JACOsub set for a 4-color (2-bitplane) screen, and you try to load in a 16-color (4-bitplane) picture, you will lose 2 biplanes of information, and the picture will look strange when it appears. 4. All pictures are treated as IFF brushes. Therefore, your picture, once loaded, will use JACOsub's color palette. THE PICTURE'S OWN COLOR PALETTE WILL BE IGNORED. Create your graphics using the SAME palette you use with JACOsub or the picture will look strange when it appears. If you want to load a picture with its own colors, use the IS directive (but then you won't be able to display text on top of it). 5. JACOsub attempts to load the IFF files as they are needed. This can cause a slight video switch delay if a time event occurs while a file is loading, even though the IFF loading routines do check the clock frequently. Keep your IFF images on a fast hard disk, or better yet, in RAM:. If you do not have sufficient memory, then do not use this directive! IS <ILBM file name> Load an IFF ILBM file into its own screen, with its own resolution and colors. This screen will temporarily replace one of the video buffers. As with IL, JACOsub assumes that the text following the IS directive contains the file name to load. JACOsub will attempt to center the picture on your screen. The IL caveats 1, 2, and 5 above apply here also, and the IS directive has some additional considerations: 1. You cannot display text on top of a picture loaded with the IS directive. Use the IL directive for this. 2. The time ranges associated with an IFF screen should NOT overlap any other time ranges. If they do, the start time for the IFF file has priority over any unrealized end times. 3. The IS directive can tax your memory even more severely than the IL directive, especially if you load a pictures like hi-res HAM images to substitute every video buffer. 4. We observe difficulty loading Extra-Halfbrite pictures. Try it for yourself. HAM and AGA images seem to work OK. >> DO NOT USE IS OR IL IN DEFAULT DIRECTIVES! ARexx communications -------------------- RX <ARexx script name> Execute the ARexx script name that follows the RX directive. You should not specify other directives on the same line. Only one RX directive may be specified per time event -- that is, if you have several lines all sharing the same start time, no more than one of them may contain an RX directive. If more than one RX directive is specified for a given start time, the one that occurs latest in the script will be used. The end time for the line is ignored, but should be larger than the start time to avoid a compiler warning. Try to make the end time equal to the next nearest start time to avoid creating unnecessary video frames. >> DO NOT USE RX IN DEFAULT DIRECTIVES! Default directives ------------------ Because all of the above directives are optional, there is one other set of directives that may be used when you do not wish to specify any: D or D0 Default. To be used if no other directives are used. You don't even need this directive at all, if your text begins with a non-alphabetic character (such as a {comment}, number, etc.). Specifying D (or nothing) will use the program's default settings. The default directive for JACOsub is normally HL1HR99VH100VT16VB16JCJBFW1F0FDFO0:2FSSE0SNCF3CB0CP0CS0:0:2 which you can change in the file JACOsub.Config, or with a #D command at the top of your script. Confused? Here they are spaced out: HL1 HR99 VH100 VT16 VB16 JC JBF W1 F0 FD FO0:2 FSSE0 SN CF3 CB0 CP0 CS0:0:2 The IFF directives and the Genlock directives should NEVER be specified globally, nor in JACOsub.Config. Dn The directives D1 - D20 may be defined with the commands #D1 - #D20. You can use these "default" directives as shorthand for more complex directives that you may need in many places. If you put two D directives in the same directive string, the latest one will be used, and any previous directives ignored. If a directive string contains conflicting information, the information occurring last will be used. For example, VTD will cause VT to be ignored in favor of the default. In the directive CF10JLCF3, CF10 will be ignored in favor of CF3. Naturally, any directive beginning with D is unaffected by the D. In the long default directive above, you can see VT16VB16. This serves to set the top-of-screen offset to 16 for later, and then sets the default vertical positioning will be 16 pixels from the bottom of the viewport. Time track ---------- Tx Designate this line as belonging to track x, where x is any of the characters 0-9, A-F (case insensitive), or punctuation. This directive is ignored when compiling and playing scripts. All titles default to T0 if no track is specified. The purpose of tracks is to let you assign unique designations to specific title sequences interwoven with others in your script so that you can time them separately. For example, suppose you need to subtitle two people talking simultaneously with music lyrics in the background. This requires three independent timing sequences. There are two ways to do this: 1. Separate blocks of titles. Without using the T directive, you must arrange each sequence as a separate block of titles (remember, JACOsub doesn't care about order of the titles in your script file -- it will sort everything out according to start and stop times). 2. One block of titles containing designated time tracks. You can weave all the titles together as one long sequence, and designate separate tracks with the T directive so that the timing procedure can figure out which titles must be timed, and which must be skipped. TRACKS WILL BE IGNORED IN ALL DEFAULT OR USER-DEFINED DIRECTIVES. Furthermore, as far as JACOsub is concerned, it's not treated as a true "directive" at all. Its only use is to flag lines for the program's timing functions. 5. SAMPLE LINES ================ These 4 lines all have the same effect. Note that any spaces after the directive and the first space after comments are ignored. 0:00:10.11 0:00:12.00 D {fudo-ikiteru} It's alive! 0:00:10.11 0:00:12.00 D {fudo-ikiteru}It's alive! 0:00:10.11 0:00:12.00 D It's alive!{line doesn't start with a comment} 0:00:10.11 0:00:12.00 {fudo-ikiteru} It's alive!{starts with a comment} If you want leading/trailing spaces, all of these lines will do the same thing (put two spaces in front of and after the text): 0:00:10.11 0:00:12.00 D ~~{fudo-ikiteru} It's alive! ~ 0:00:10.11 0:00:12.00 D {fudo-ikiteru}~~It's alive!~~ 0:00:10.11 0:00:12.00 D {fudo-ikiteru} ~~It's alive!~~ 0:00:10.11 0:00:12.00 D ~ It's alive!~~ 0:00:10.11 0:00:12.00 ~~{fudo-ikiteru} It's alive! ~ 0:00:10.11 0:00:12.00 {fudo-ikiteru}~ It's alive!~~ 0:00:10.11 0:00:12.00 {fudo-ikiteru} ~~It's alive!~~ 0:00:10.11 0:00:12.00 {fudo-ikiteru} It's alive!~~ THE FOLLOWING LINE IS BAD. It needs either a directive after the timing numbers, or a comment to indicate that subtitle text follows the timing numbers. Any alphabet character (A-Z, a-z) following the timing numbers MUST be part of a directive. 0:00:10.11 0:00:12.00 It's alive! For the next line, use color 1 for the font face color, start the subtitle at the top of the screen and leave the other defaults alone, and cause one word to be displayed in italics: 0:02:23.23 0:02:25.01 cf1vt {thug1-nani} Whaddaya \Imean\N, ``please?'' Note: Normal quotation marks ("like this") may be used, but using a double grave and a double apostrophe, as in the line above, looks more professional on the screen. Just make sure that the grave looks like an upside-down apostrophe in your font, and that both characters occupy a narrow space. The JACOsub fonts are designed this way. Additional note (THIS IS ONE OF THE BIG FEATURES OF JACOsub): Timings may overlap! The software will handle overlapping text displays properly, but you must be sure to position your subtitles so that these separate text events do not physically overlap on the screen. You can arrange timed lines in any order you want, separate overlapped events into groups, or whatever. The program will handle it. 6. CREDITS =========== The original JACOsub format was dreamed up by Alex Matulich and Daric Koslowski, before any code was ever written for JACOsub. Yes, this was the second step! (The first was to create the fonts.) Beta testers and users have been very helpful in expanding and improving the specification into what it is today. User feedback has played a large role in the development of the software and the script format. The entire JACOsub project has been largely user-driven. End of JScripts.doc.